home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / dev / gcc / gcc263_src.lha / gcc-2.6.3 / gcc.info-17 < prev    next >
Encoding:
GNU Info File  |  1994-11-23  |  45.8 KB  |  1,054 lines
  1. This is Info file gcc.info, produced by Makeinfo-1.55 from the input
  2. file gcc.texi.
  3.  
  4.    This file documents the use and the internals of the GNU compiler.
  5.  
  6.    Published by the Free Software Foundation 675 Massachusetts Avenue
  7. Cambridge, MA 02139 USA
  8.  
  9.    Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation,
  10. Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided also
  18. that the sections entitled "GNU General Public License," "Funding for
  19. Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
  20. included exactly as in the original, and provided that the entire
  21. resulting derived work is distributed under the terms of a permission
  22. notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that the sections entitled "GNU General Public
  27. License," "Funding for Free Software," and "Protect Your Freedom--Fight
  28. `Look And Feel'", and this permission notice, may be included in
  29. translations approved by the Free Software Foundation instead of in the
  30. original English.
  31.  
  32. 
  33. File: gcc.info,  Node: Expander Definitions,  Next: Insn Splitting,  Prev: Peephole Definitions,  Up: Machine Desc
  34.  
  35. Defining RTL Sequences for Code Generation
  36. ==========================================
  37.  
  38.    On some target machines, some standard pattern names for RTL
  39. generation cannot be handled with single insn, but a sequence of RTL
  40. insns can represent them.  For these target machines, you can write a
  41. `define_expand' to specify how to generate the sequence of RTL.
  42.  
  43.    A `define_expand' is an RTL expression that looks almost like a
  44. `define_insn'; but, unlike the latter, a `define_expand' is used only
  45. for RTL generation and it can produce more than one RTL insn.
  46.  
  47.    A `define_expand' RTX has four operands:
  48.  
  49.    * The name.  Each `define_expand' must have a name, since the only
  50.      use for it is to refer to it by name.
  51.  
  52.    * The RTL template.  This is just like the RTL template for a
  53.      `define_peephole' in that it is a vector of RTL expressions each
  54.      being one insn.
  55.  
  56.    * The condition, a string containing a C expression.  This
  57.      expression is used to express how the availability of this pattern
  58.      depends on subclasses of target machine, selected by command-line
  59.      options when GNU CC is run.  This is just like the condition of a
  60.      `define_insn' that has a standard name.
  61.  
  62.    * The preparation statements, a string containing zero or more C
  63.      statements which are to be executed before RTL code is generated
  64.      from the RTL template.
  65.  
  66.      Usually these statements prepare temporary registers for use as
  67.      internal operands in the RTL template, but they can also generate
  68.      RTL insns directly by calling routines such as `emit_insn', etc.
  69.      Any such insns precede the ones that come from the RTL template.
  70.  
  71.    Every RTL insn emitted by a `define_expand' must match some
  72. `define_insn' in the machine description.  Otherwise, the compiler will
  73. crash when trying to generate code for the insn or trying to optimize
  74. it.
  75.  
  76.    The RTL template, in addition to controlling generation of RTL insns,
  77. also describes the operands that need to be specified when this pattern
  78. is used.  In particular, it gives a predicate for each operand.
  79.  
  80.    A true operand, which needs to be specified in order to generate RTL
  81. from the pattern, should be described with a `match_operand' in its
  82. first occurrence in the RTL template.  This enters information on the
  83. operand's predicate into the tables that record such things.  GNU CC
  84. uses the information to preload the operand into a register if that is
  85. required for valid RTL code.  If the operand is referred to more than
  86. once, subsequent references should use `match_dup'.
  87.  
  88.    The RTL template may also refer to internal "operands" which are
  89. temporary registers or labels used only within the sequence made by the
  90. `define_expand'.  Internal operands are substituted into the RTL
  91. template with `match_dup', never with `match_operand'.  The values of
  92. the internal operands are not passed in as arguments by the compiler
  93. when it requests use of this pattern.  Instead, they are computed
  94. within the pattern, in the preparation statements.  These statements
  95. compute the values and store them into the appropriate elements of
  96. `operands' so that `match_dup' can find them.
  97.  
  98.    There are two special macros defined for use in the preparation
  99. statements: `DONE' and `FAIL'.  Use them with a following semicolon, as
  100. a statement.
  101.  
  102. `DONE'
  103.      Use the `DONE' macro to end RTL generation for the pattern.  The
  104.      only RTL insns resulting from the pattern on this occasion will be
  105.      those already emitted by explicit calls to `emit_insn' within the
  106.      preparation statements; the RTL template will not be generated.
  107.  
  108. `FAIL'
  109.      Make the pattern fail on this occasion.  When a pattern fails, it
  110.      means that the pattern was not truly available.  The calling
  111.      routines in the compiler will try other strategies for code
  112.      generation using other patterns.
  113.  
  114.      Failure is currently supported only for binary (addition,
  115.      multiplication, shifting, etc.) and bitfield (`extv', `extzv', and
  116.      `insv') operations.
  117.  
  118.    Here is an example, the definition of left-shift for the SPUR chip:
  119.  
  120.      (define_expand "ashlsi3"
  121.        [(set (match_operand:SI 0 "register_operand" "")
  122.              (ashift:SI
  123.  
  124.      (match_operand:SI 1 "register_operand" "")
  125.                (match_operand:SI 2 "nonmemory_operand" "")))]
  126.        ""
  127.        "
  128.  
  129.      {
  130.        if (GET_CODE (operands[2]) != CONST_INT
  131.            || (unsigned) INTVAL (operands[2]) > 3)
  132.          FAIL;
  133.      }")
  134.  
  135. This example uses `define_expand' so that it can generate an RTL insn
  136. for shifting when the shift-count is in the supported range of 0 to 3
  137. but fail in other cases where machine insns aren't available.  When it
  138. fails, the compiler tries another strategy using different patterns
  139. (such as, a library call).
  140.  
  141.    If the compiler were able to handle nontrivial condition-strings in
  142. patterns with names, then it would be possible to use a `define_insn'
  143. in that case.  Here is another case (zero-extension on the 68000) which
  144. makes more use of the power of `define_expand':
  145.  
  146.      (define_expand "zero_extendhisi2"
  147.        [(set (match_operand:SI 0 "general_operand" "")
  148.              (const_int 0))
  149.         (set (strict_low_part
  150.                (subreg:HI
  151.                  (match_dup 0)
  152.                  0))
  153.              (match_operand:HI 1 "general_operand" ""))]
  154.        ""
  155.        "operands[1] = make_safe_from (operands[1], operands[0]);")
  156.  
  157. Here two RTL insns are generated, one to clear the entire output operand
  158. and the other to copy the input operand into its low half.  This
  159. sequence is incorrect if the input operand refers to [the old value of]
  160. the output operand, so the preparation statement makes sure this isn't
  161. so.  The function `make_safe_from' copies the `operands[1]' into a
  162. temporary register if it refers to `operands[0]'.  It does this by
  163. emitting another RTL insn.
  164.  
  165.    Finally, a third example shows the use of an internal operand.
  166. Zero-extension on the SPUR chip is done by `and'-ing the result against
  167. a halfword mask.  But this mask cannot be represented by a `const_int'
  168. because the constant value is too large to be legitimate on this
  169. machine.  So it must be copied into a register with `force_reg' and
  170. then the register used in the `and'.
  171.  
  172.      (define_expand "zero_extendhisi2"
  173.        [(set (match_operand:SI 0 "register_operand" "")
  174.              (and:SI (subreg:SI
  175.                        (match_operand:HI 1 "register_operand" "")
  176.                        0)
  177.                      (match_dup 2)))]
  178.        ""
  179.        "operands[2]
  180.           = force_reg (SImode, gen_rtx (CONST_INT,
  181.                                         VOIDmode, 65535)); ")
  182.  
  183.    *Note:* If the `define_expand' is used to serve a standard binary or
  184. unary arithmetic operation or a bitfield operation, then the last insn
  185. it generates must not be a `code_label', `barrier' or `note'.  It must
  186. be an `insn', `jump_insn' or `call_insn'.  If you don't need a real insn
  187. at the end, emit an insn to copy the result of the operation into
  188. itself.  Such an insn will generate no code, but it can avoid problems
  189. in the compiler.
  190.  
  191. 
  192. File: gcc.info,  Node: Insn Splitting,  Next: Insn Attributes,  Prev: Expander Definitions,  Up: Machine Desc
  193.  
  194. Defining How to Split Instructions
  195. ==================================
  196.  
  197.    There are two cases where you should specify how to split a pattern
  198. into multiple insns.  On machines that have instructions requiring delay
  199. slots (*note Delay Slots::.) or that have instructions whose output is
  200. not available for multiple cycles (*note Function Units::.), the
  201. compiler phases that optimize these cases need to be able to move insns
  202. into one-instruction delay slots.  However, some insns may generate
  203. more than one machine instruction.  These insns cannot be placed into a
  204. delay slot.
  205.  
  206.    Often you can rewrite the single insn as a list of individual insns,
  207. each corresponding to one machine instruction.  The disadvantage of
  208. doing so is that it will cause the compilation to be slower and require
  209. more space.  If the resulting insns are too complex, it may also
  210. suppress some optimizations.  The compiler splits the insn if there is a
  211. reason to believe that it might improve instruction or delay slot
  212. scheduling.
  213.  
  214.    The insn combiner phase also splits putative insns.  If three insns
  215. are merged into one insn with a complex expression that cannot be
  216. matched by some `define_insn' pattern, the combiner phase attempts to
  217. split the complex pattern into two insns that are recognized.  Usually
  218. it can break the complex pattern into two patterns by splitting out some
  219. subexpression.  However, in some other cases, such as performing an
  220. addition of a large constant in two insns on a RISC machine, the way to
  221. split the addition into two insns is machine-dependent.
  222.  
  223.    The `define_split' definition tells the compiler how to split a
  224. complex insn into several simpler insns.  It looks like this:
  225.  
  226.      (define_split
  227.        [INSN-PATTERN]
  228.        "CONDITION"
  229.        [NEW-INSN-PATTERN-1
  230.         NEW-INSN-PATTERN-2
  231.         ...]
  232.        "PREPARATION STATEMENTS")
  233.  
  234.    INSN-PATTERN is a pattern that needs to be split and CONDITION is
  235. the final condition to be tested, as in a `define_insn'.  When an insn
  236. matching INSN-PATTERN and satisfying CONDITION is found, it is replaced
  237. in the insn list with the insns given by NEW-INSN-PATTERN-1,
  238. NEW-INSN-PATTERN-2, etc.
  239.  
  240.    The PREPARATION STATEMENTS are similar to those statements that are
  241. specified for `define_expand' (*note Expander Definitions::.) and are
  242. executed before the new RTL is generated to prepare for the generated
  243. code or emit some insns whose pattern is not fixed.  Unlike those in
  244. `define_expand', however, these statements must not generate any new
  245. pseudo-registers.  Once reload has completed, they also must not
  246. allocate any space in the stack frame.
  247.  
  248.    Patterns are matched against INSN-PATTERN in two different
  249. circumstances.  If an insn needs to be split for delay slot scheduling
  250. or insn scheduling, the insn is already known to be valid, which means
  251. that it must have been matched by some `define_insn' and, if
  252. `reload_completed' is non-zero, is known to satisfy the constraints of
  253. that `define_insn'.  In that case, the new insn patterns must also be
  254. insns that are matched by some `define_insn' and, if `reload_completed'
  255. is non-zero, must also satisfy the constraints of those definitions.
  256.  
  257.    As an example of this usage of `define_split', consider the following
  258. example from `a29k.md', which splits a `sign_extend' from `HImode' to
  259. `SImode' into a pair of shift insns:
  260.  
  261.      (define_split
  262.        [(set (match_operand:SI 0 "gen_reg_operand" "")
  263.              (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
  264.        ""
  265.        [(set (match_dup 0)
  266.              (ashift:SI (match_dup 1)
  267.                         (const_int 16)))
  268.         (set (match_dup 0)
  269.              (ashiftrt:SI (match_dup 0)
  270.                           (const_int 16)))]
  271.        "
  272.      { operands[1] = gen_lowpart (SImode, operands[1]); }")
  273.  
  274.    When the combiner phase tries to split an insn pattern, it is always
  275. the case that the pattern is *not* matched by any `define_insn'.  The
  276. combiner pass first tries to split a single `set' expression and then
  277. the same `set' expression inside a `parallel', but followed by a
  278. `clobber' of a pseudo-reg to use as a scratch register.  In these
  279. cases, the combiner expects exactly two new insn patterns to be
  280. generated.  It will verify that these patterns match some `define_insn'
  281. definitions, so you need not do this test in the `define_split' (of
  282. course, there is no point in writing a `define_split' that will never
  283. produce insns that match).
  284.  
  285.    Here is an example of this use of `define_split', taken from
  286. `rs6000.md':
  287.  
  288.      (define_split
  289.        [(set (match_operand:SI 0 "gen_reg_operand" "")
  290.              (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
  291.                       (match_operand:SI 2 "non_add_cint_operand" "")))]
  292.        ""
  293.        [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
  294.         (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
  295.      "
  296.      {
  297.        int low = INTVAL (operands[2]) & 0xffff;
  298.        int high = (unsigned) INTVAL (operands[2]) >> 16;
  299.      
  300.        if (low & 0x8000)
  301.          high++, low |= 0xffff0000;
  302.      
  303.        operands[3] = gen_rtx (CONST_INT, VOIDmode, high << 16);
  304.        operands[4] = gen_rtx (CONST_INT, VOIDmode, low);
  305.      }")
  306.  
  307.    Here the predicate `non_add_cint_operand' matches any `const_int'
  308. that is *not* a valid operand of a single add insn.  The add with the
  309. smaller displacement is written so that it can be substituted into the
  310. address of a subsequent operation.
  311.  
  312.    An example that uses a scratch register, from the same file,
  313. generates an equality comparison of a register and a large constant:
  314.  
  315.      (define_split
  316.        [(set (match_operand:CC 0 "cc_reg_operand" "")
  317.              (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
  318.                          (match_operand:SI 2 "non_short_cint_operand" "")))
  319.         (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
  320.        "find_single_use (operands[0], insn, 0)
  321.         && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
  322.             || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
  323.        [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
  324.         (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
  325.        "
  326.      {
  327.        /* Get the constant we are comparing against, C, and see what it
  328.           looks like sign-extended to 16 bits.  Then see what constant
  329.           could be XOR'ed with C to get the sign-extended value.  */
  330.      
  331.        int c = INTVAL (operands[2]);
  332.        int sextc = (c << 16) >> 16;
  333.        int xorv = c ^ sextc;
  334.      
  335.        operands[4] = gen_rtx (CONST_INT, VOIDmode, xorv);
  336.        operands[5] = gen_rtx (CONST_INT, VOIDmode, sextc);
  337.      }")
  338.  
  339.    To avoid confusion, don't write a single `define_split' that accepts
  340. some insns that match some `define_insn' as well as some insns that
  341. don't.  Instead, write two separate `define_split' definitions, one for
  342. the insns that are valid and one for the insns that are not valid.
  343.  
  344. 
  345. File: gcc.info,  Node: Insn Attributes,  Prev: Insn Splitting,  Up: Machine Desc
  346.  
  347. Instruction Attributes
  348. ======================
  349.  
  350.    In addition to describing the instruction supported by the target
  351. machine, the `md' file also defines a group of "attributes" and a set of
  352. values for each.  Every generated insn is assigned a value for each
  353. attribute.  One possible attribute would be the effect that the insn
  354. has on the machine's condition code.  This attribute can then be used
  355. by `NOTICE_UPDATE_CC' to track the condition codes.
  356.  
  357. * Menu:
  358.  
  359. * Defining Attributes:: Specifying attributes and their values.
  360. * Expressions::         Valid expressions for attribute values.
  361. * Tagging Insns::       Assigning attribute values to insns.
  362. * Attr Example::        An example of assigning attributes.
  363. * Insn Lengths::        Computing the length of insns.
  364. * Constant Attributes:: Defining attributes that are constant.
  365. * Delay Slots::         Defining delay slots required for a machine.
  366. * Function Units::      Specifying information for insn scheduling.
  367.  
  368. 
  369. File: gcc.info,  Node: Defining Attributes,  Next: Expressions,  Up: Insn Attributes
  370.  
  371. Defining Attributes and their Values
  372. ------------------------------------
  373.  
  374.    The `define_attr' expression is used to define each attribute
  375. required by the target machine.  It looks like:
  376.  
  377.      (define_attr NAME LIST-OF-VALUES DEFAULT)
  378.  
  379.    NAME is a string specifying the name of the attribute being defined.
  380.  
  381.    LIST-OF-VALUES is either a string that specifies a comma-separated
  382. list of values that can be assigned to the attribute, or a null string
  383. to indicate that the attribute takes numeric values.
  384.  
  385.    DEFAULT is an attribute expression that gives the value of this
  386. attribute for insns that match patterns whose definition does not
  387. include an explicit value for this attribute.  *Note Attr Example::,
  388. for more information on the handling of defaults.  *Note Constant
  389. Attributes::, for information on attributes that do not depend on any
  390. particular insn.
  391.  
  392.    For each defined attribute, a number of definitions are written to
  393. the `insn-attr.h' file.  For cases where an explicit set of values is
  394. specified for an attribute, the following are defined:
  395.  
  396.    * A `#define' is written for the symbol `HAVE_ATTR_NAME'.
  397.  
  398.    * An enumeral class is defined for `attr_NAME' with elements of the
  399.      form `UPPER-NAME_UPPER-VALUE' where the attribute name and value
  400.      are first converted to upper case.
  401.  
  402.    * A function `get_attr_NAME' is defined that is passed an insn and
  403.      returns the attribute value for that insn.
  404.  
  405.    For example, if the following is present in the `md' file:
  406.  
  407.      (define_attr "type" "branch,fp,load,store,arith" ...)
  408.  
  409. the following lines will be written to the file `insn-attr.h'.
  410.  
  411.      #define HAVE_ATTR_type
  412.      enum attr_type {TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
  413.                       TYPE_STORE, TYPE_ARITH};
  414.      extern enum attr_type get_attr_type ();
  415.  
  416.    If the attribute takes numeric values, no `enum' type will be
  417. defined and the function to obtain the attribute's value will return
  418. `int'.
  419.  
  420. 
  421. File: gcc.info,  Node: Expressions,  Next: Tagging Insns,  Prev: Defining Attributes,  Up: Insn Attributes
  422.  
  423. Attribute Expressions
  424. ---------------------
  425.  
  426.    RTL expressions used to define attributes use the codes described
  427. above plus a few specific to attribute definitions, to be discussed
  428. below.  Attribute value expressions must have one of the following
  429. forms:
  430.  
  431. `(const_int I)'
  432.      The integer I specifies the value of a numeric attribute.  I must
  433.      be non-negative.
  434.  
  435.      The value of a numeric attribute can be specified either with a
  436.      `const_int' or as an integer represented as a string in
  437.      `const_string', `eq_attr' (see below), and `set_attr' (*note
  438.      Tagging Insns::.) expressions.
  439.  
  440. `(const_string VALUE)'
  441.      The string VALUE specifies a constant attribute value.  If VALUE
  442.      is specified as `"*"', it means that the default value of the
  443.      attribute is to be used for the insn containing this expression.
  444.      `"*"' obviously cannot be used in the DEFAULT expression of a
  445.      `define_attr'.
  446.  
  447.      If the attribute whose value is being specified is numeric, VALUE
  448.      must be a string containing a non-negative integer (normally
  449.      `const_int' would be used in this case).  Otherwise, it must
  450.      contain one of the valid values for the attribute.
  451.  
  452. `(if_then_else TEST TRUE-VALUE FALSE-VALUE)'
  453.      TEST specifies an attribute test, whose format is defined below.
  454.      The value of this expression is TRUE-VALUE if TEST is true,
  455.      otherwise it is FALSE-VALUE.
  456.  
  457. `(cond [TEST1 VALUE1 ...] DEFAULT)'
  458.      The first operand of this expression is a vector containing an even
  459.      number of expressions and consisting of pairs of TEST and VALUE
  460.      expressions.  The value of the `cond' expression is that of the
  461.      VALUE corresponding to the first true TEST expression.  If none of
  462.      the TEST expressions are true, the value of the `cond' expression
  463.      is that of the DEFAULT expression.
  464.  
  465.    TEST expressions can have one of the following forms:
  466.  
  467. `(const_int I)'
  468.      This test is true if I is non-zero and false otherwise.
  469.  
  470. `(not TEST)'
  471. `(ior TEST1 TEST2)'
  472. `(and TEST1 TEST2)'
  473.      These tests are true if the indicated logical function is true.
  474.  
  475. `(match_operand:M N PRED CONSTRAINTS)'
  476.      This test is true if operand N of the insn whose attribute value
  477.      is being determined has mode M (this part of the test is ignored
  478.      if M is `VOIDmode') and the function specified by the string PRED
  479.      returns a non-zero value when passed operand N and mode M (this
  480.      part of the test is ignored if PRED is the null string).
  481.  
  482.      The CONSTRAINTS operand is ignored and should be the null string.
  483.  
  484. `(le ARITH1 ARITH2)'
  485. `(leu ARITH1 ARITH2)'
  486. `(lt ARITH1 ARITH2)'
  487. `(ltu ARITH1 ARITH2)'
  488. `(gt ARITH1 ARITH2)'
  489. `(gtu ARITH1 ARITH2)'
  490. `(ge ARITH1 ARITH2)'
  491. `(geu ARITH1 ARITH2)'
  492. `(ne ARITH1 ARITH2)'
  493. `(eq ARITH1 ARITH2)'
  494.      These tests are true if the indicated comparison of the two
  495.      arithmetic expressions is true.  Arithmetic expressions are formed
  496.      with `plus', `minus', `mult', `div', `mod', `abs', `neg', `and',
  497.      `ior', `xor', `not', `ashift', `lshiftrt', and `ashiftrt'
  498.      expressions.
  499.  
  500.      `const_int' and `symbol_ref' are always valid terms (*note Insn
  501.      Lengths::.,for additional forms).  `symbol_ref' is a string
  502.      denoting a C expression that yields an `int' when evaluated by the
  503.      `get_attr_...' routine.  It should normally be a global variable.
  504.  
  505. `(eq_attr NAME VALUE)'
  506.      NAME is a string specifying the name of an attribute.
  507.  
  508.      VALUE is a string that is either a valid value for attribute NAME,
  509.      a comma-separated list of values, or `!' followed by a value or
  510.      list.  If VALUE does not begin with a `!', this test is true if
  511.      the value of the NAME attribute of the current insn is in the list
  512.      specified by VALUE.  If VALUE begins with a `!', this test is true
  513.      if the attribute's value is *not* in the specified list.
  514.  
  515.      For example,
  516.  
  517.           (eq_attr "type" "load,store")
  518.  
  519.      is equivalent to
  520.  
  521.           (ior (eq_attr "type" "load") (eq_attr "type" "store"))
  522.  
  523.      If NAME specifies an attribute of `alternative', it refers to the
  524.      value of the compiler variable `which_alternative' (*note Output
  525.      Statement::.) and the values must be small integers.  For example,
  526.  
  527.           (eq_attr "alternative" "2,3")
  528.  
  529.      is equivalent to
  530.  
  531.           (ior (eq (symbol_ref "which_alternative") (const_int 2))
  532.                (eq (symbol_ref "which_alternative") (const_int 3)))
  533.  
  534.      Note that, for most attributes, an `eq_attr' test is simplified in
  535.      cases where the value of the attribute being tested is known for
  536.      all insns matching a particular pattern.  This is by far the most
  537.      common case.
  538.  
  539. `(attr_flag NAME)'
  540.      The value of an `attr_flag' expression is true if the flag
  541.      specified by NAME is true for the `insn' currently being scheduled.
  542.  
  543.      NAME is a string specifying one of a fixed set of flags to test.
  544.      Test the flags `forward' and `backward' to determine the direction
  545.      of a conditional branch.  Test the flags `very_likely', `likely',
  546.      `very_unlikely', and `unlikely' to determine if a conditional
  547.      branch is expected to be taken.
  548.  
  549.      If the `very_likely' flag is true, then the `likely' flag is also
  550.      true.  Likewise for the `very_unlikely' and `unlikely' flags.
  551.  
  552.      This example describes a conditional branch delay slot which can
  553.      be nullified for forward branches that are taken (annul-true) or
  554.      for backward branches which are not taken (annul-false).
  555.  
  556.           (define_delay (eq_attr "type" "cbranch")
  557.             [(eq_attr "in_branch_delay" "true")
  558.              (and (eq_attr "in_branch_delay" "true")
  559.                   (attr_flag "forward"))
  560.              (and (eq_attr "in_branch_delay" "true")
  561.                   (attr_flag "backward"))])
  562.  
  563.      The `forward' and `backward' flags are false if the current `insn'
  564.      being scheduled is not a conditional branch.
  565.  
  566.      The `very_likely' and `likely' flags are true if the `insn' being
  567.      scheduled is not a conditional branch.  The The `very_unlikely'
  568.      and `unlikely' flags are false if the `insn' being scheduled is
  569.      not a conditional branch.
  570.  
  571.      `attr_flag' is only used during delay slot scheduling and has no
  572.      meaning to other passes of the compiler.
  573.  
  574. 
  575. File: gcc.info,  Node: Tagging Insns,  Next: Attr Example,  Prev: Expressions,  Up: Insn Attributes
  576.  
  577. Assigning Attribute Values to Insns
  578. -----------------------------------
  579.  
  580.    The value assigned to an attribute of an insn is primarily
  581. determined by which pattern is matched by that insn (or which
  582. `define_peephole' generated it).  Every `define_insn' and
  583. `define_peephole' can have an optional last argument to specify the
  584. values of attributes for matching insns.  The value of any attribute
  585. not specified in a particular insn is set to the default value for that
  586. attribute, as specified in its `define_attr'.  Extensive use of default
  587. values for attributes permits the specification of the values for only
  588. one or two attributes in the definition of most insn patterns, as seen
  589. in the example in the next section.
  590.  
  591.    The optional last argument of `define_insn' and `define_peephole' is
  592. a vector of expressions, each of which defines the value for a single
  593. attribute.  The most general way of assigning an attribute's value is
  594. to use a `set' expression whose first operand is an `attr' expression
  595. giving the name of the attribute being set.  The second operand of the
  596. `set' is an attribute expression (*note Expressions::.) giving the
  597. value of the attribute.
  598.  
  599.    When the attribute value depends on the `alternative' attribute
  600. (i.e., which is the applicable alternative in the constraint of the
  601. insn), the `set_attr_alternative' expression can be used.  It allows
  602. the specification of a vector of attribute expressions, one for each
  603. alternative.
  604.  
  605.    When the generality of arbitrary attribute expressions is not
  606. required, the simpler `set_attr' expression can be used, which allows
  607. specifying a string giving either a single attribute value or a list of
  608. attribute values, one for each alternative.
  609.  
  610.    The form of each of the above specifications is shown below.  In
  611. each case, NAME is a string specifying the attribute to be set.
  612.  
  613. `(set_attr NAME VALUE-STRING)'
  614.      VALUE-STRING is either a string giving the desired attribute value,
  615.      or a string containing a comma-separated list giving the values for
  616.      succeeding alternatives.  The number of elements must match the
  617.      number of alternatives in the constraint of the insn pattern.
  618.  
  619.      Note that it may be useful to specify `*' for some alternative, in
  620.      which case the attribute will assume its default value for insns
  621.      matching that alternative.
  622.  
  623. `(set_attr_alternative NAME [VALUE1 VALUE2 ...])'
  624.      Depending on the alternative of the insn, the value will be one of
  625.      the specified values.  This is a shorthand for using a `cond' with
  626.      tests on the `alternative' attribute.
  627.  
  628. `(set (attr NAME) VALUE)'
  629.      The first operand of this `set' must be the special RTL expression
  630.      `attr', whose sole operand is a string giving the name of the
  631.      attribute being set.  VALUE is the value of the attribute.
  632.  
  633.    The following shows three different ways of representing the same
  634. attribute value specification:
  635.  
  636.      (set_attr "type" "load,store,arith")
  637.      
  638.      (set_attr_alternative "type"
  639.                            [(const_string "load") (const_string "store")
  640.                             (const_string "arith")])
  641.      
  642.      (set (attr "type")
  643.           (cond [(eq_attr "alternative" "1") (const_string "load")
  644.                  (eq_attr "alternative" "2") (const_string "store")]
  645.                 (const_string "arith")))
  646.  
  647.    The `define_asm_attributes' expression provides a mechanism to
  648. specify the attributes assigned to insns produced from an `asm'
  649. statement.  It has the form:
  650.  
  651.      (define_asm_attributes [ATTR-SETS])
  652.  
  653. where ATTR-SETS is specified the same as for both the `define_insn' and
  654. the `define_peephole' expressions.
  655.  
  656.    These values will typically be the "worst case" attribute values.
  657. For example, they might indicate that the condition code will be
  658. clobbered.
  659.  
  660.    A specification for a `length' attribute is handled specially.  The
  661. way to compute the length of an `asm' insn is to multiply the length
  662. specified in the expression `define_asm_attributes' by the number of
  663. machine instructions specified in the `asm' statement, determined by
  664. counting the number of semicolons and newlines in the string.
  665. Therefore, the value of the `length' attribute specified in a
  666. `define_asm_attributes' should be the maximum possible length of a
  667. single machine instruction.
  668.  
  669. 
  670. File: gcc.info,  Node: Attr Example,  Next: Insn Lengths,  Prev: Tagging Insns,  Up: Insn Attributes
  671.  
  672. Example of Attribute Specifications
  673. -----------------------------------
  674.  
  675.    The judicious use of defaulting is important in the efficient use of
  676. insn attributes.  Typically, insns are divided into "types" and an
  677. attribute, customarily called `type', is used to represent this value.
  678. This attribute is normally used only to define the default value for
  679. other attributes.  An example will clarify this usage.
  680.  
  681.    Assume we have a RISC machine with a condition code and in which only
  682. full-word operations are performed in registers.  Let us assume that we
  683. can divide all insns into loads, stores, (integer) arithmetic
  684. operations, floating point operations, and branches.
  685.  
  686.    Here we will concern ourselves with determining the effect of an
  687. insn on the condition code and will limit ourselves to the following
  688. possible effects:  The condition code can be set unpredictably
  689. (clobbered), not be changed, be set to agree with the results of the
  690. operation, or only changed if the item previously set into the
  691. condition code has been modified.
  692.  
  693.    Here is part of a sample `md' file for such a machine:
  694.  
  695.      (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
  696.      
  697.      (define_attr "cc" "clobber,unchanged,set,change0"
  698.                   (cond [(eq_attr "type" "load")
  699.                              (const_string "change0")
  700.                          (eq_attr "type" "store,branch")
  701.                              (const_string "unchanged")
  702.                          (eq_attr "type" "arith")
  703.                              (if_then_else (match_operand:SI 0 "" "")
  704.                                            (const_string "set")
  705.                                            (const_string "clobber"))]
  706.                         (const_string "clobber")))
  707.      
  708.      (define_insn ""
  709.        [(set (match_operand:SI 0 "general_operand" "=r,r,m")
  710.              (match_operand:SI 1 "general_operand" "r,m,r"))]
  711.        ""
  712.        "@
  713.         move %0,%1
  714.         load %0,%1
  715.         store %0,%1"
  716.        [(set_attr "type" "arith,load,store")])
  717.  
  718.    Note that we assume in the above example that arithmetic operations
  719. performed on quantities smaller than a machine word clobber the
  720. condition code since they will set the condition code to a value
  721. corresponding to the full-word result.
  722.  
  723. 
  724. File: gcc.info,  Node: Insn Lengths,  Next: Constant Attributes,  Prev: Attr Example,  Up: Insn Attributes
  725.  
  726. Computing the Length of an Insn
  727. -------------------------------
  728.  
  729.    For many machines, multiple types of branch instructions are
  730. provided, each for different length branch displacements.  In most
  731. cases, the assembler will choose the correct instruction to use.
  732. However, when the assembler cannot do so, GCC can when a special
  733. attribute, the `length' attribute, is defined.  This attribute must be
  734. defined to have numeric values by specifying a null string in its
  735. `define_attr'.
  736.  
  737.    In the case of the `length' attribute, two additional forms of
  738. arithmetic terms are allowed in test expressions:
  739.  
  740. `(match_dup N)'
  741.      This refers to the address of operand N of the current insn, which
  742.      must be a `label_ref'.
  743.  
  744. `(pc)'
  745.      This refers to the address of the *current* insn.  It might have
  746.      been more consistent with other usage to make this the address of
  747.      the *next* insn but this would be confusing because the length of
  748.      the current insn is to be computed.
  749.  
  750.    For normal insns, the length will be determined by value of the
  751. `length' attribute.  In the case of `addr_vec' and `addr_diff_vec' insn
  752. patterns, the length is computed as the number of vectors multiplied by
  753. the size of each vector.
  754.  
  755.    Lengths are measured in addressable storage units (bytes).
  756.  
  757.    The following macros can be used to refine the length computation:
  758.  
  759. `FIRST_INSN_ADDRESS'
  760.      When the `length' insn attribute is used, this macro specifies the
  761.      value to be assigned to the address of the first insn in a
  762.      function.  If not specified, 0 is used.
  763.  
  764. `ADJUST_INSN_LENGTH (INSN, LENGTH)'
  765.      If defined, modifies the length assigned to instruction INSN as a
  766.      function of the context in which it is used.  LENGTH is an lvalue
  767.      that contains the initially computed length of the insn and should
  768.      be updated with the correct length of the insn.  If updating is
  769.      required, INSN must not be a varying-length insn.
  770.  
  771.      This macro will normally not be required.  A case in which it is
  772.      required is the ROMP.  On this machine, the size of an `addr_vec'
  773.      insn must be increased by two to compensate for the fact that
  774.      alignment may be required.
  775.  
  776.    The routine that returns `get_attr_length' (the value of the
  777. `length' attribute) can be used by the output routine to determine the
  778. form of the branch instruction to be written, as the example below
  779. illustrates.
  780.  
  781.    As an example of the specification of variable-length branches,
  782. consider the IBM 360.  If we adopt the convention that a register will
  783. be set to the starting address of a function, we can jump to labels
  784. within 4k of the start using a four-byte instruction.  Otherwise, we
  785. need a six-byte sequence to load the address from memory and then
  786. branch to it.
  787.  
  788.    On such a machine, a pattern for a branch instruction might be
  789. specified as follows:
  790.  
  791.      (define_insn "jump"
  792.        [(set (pc)
  793.              (label_ref (match_operand 0 "" "")))]
  794.        ""
  795.        "*
  796.      {
  797.         return (get_attr_length (insn) == 4
  798.                 ? \"b %l0\" : \"l r15,=a(%l0); br r15\");
  799.      }"
  800.        [(set (attr "length") (if_then_else (lt (match_dup 0) (const_int 4096))
  801.                                            (const_int 4)
  802.                                            (const_int 6)))])
  803.  
  804. 
  805. File: gcc.info,  Node: Constant Attributes,  Next: Delay Slots,  Prev: Insn Lengths,  Up: Insn Attributes
  806.  
  807. Constant Attributes
  808. -------------------
  809.  
  810.    A special form of `define_attr', where the expression for the
  811. default value is a `const' expression, indicates an attribute that is
  812. constant for a given run of the compiler.  Constant attributes may be
  813. used to specify which variety of processor is used.  For example,
  814.  
  815.      (define_attr "cpu" "m88100,m88110,m88000"
  816.       (const
  817.        (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
  818.               (symbol_ref "TARGET_88110") (const_string "m88110")]
  819.              (const_string "m88000"))))
  820.      
  821.      (define_attr "memory" "fast,slow"
  822.       (const
  823.        (if_then_else (symbol_ref "TARGET_FAST_MEM")
  824.                      (const_string "fast")
  825.                      (const_string "slow"))))
  826.  
  827.    The routine generated for constant attributes has no parameters as it
  828. does not depend on any particular insn.  RTL expressions used to define
  829. the value of a constant attribute may use the `symbol_ref' form, but
  830. may not use either the `match_operand' form or `eq_attr' forms
  831. involving insn attributes.
  832.  
  833. 
  834. File: gcc.info,  Node: Delay Slots,  Next: Function Units,  Prev: Constant Attributes,  Up: Insn Attributes
  835.  
  836. Delay Slot Scheduling
  837. ---------------------
  838.  
  839.    The insn attribute mechanism can be used to specify the requirements
  840. for delay slots, if any, on a target machine.  An instruction is said to
  841. require a "delay slot" if some instructions that are physically after
  842. the instruction are executed as if they were located before it.
  843. Classic examples are branch and call instructions, which often execute
  844. the following instruction before the branch or call is performed.
  845.  
  846.    On some machines, conditional branch instructions can optionally
  847. "annul" instructions in the delay slot.  This means that the
  848. instruction will not be executed for certain branch outcomes.  Both
  849. instructions that annul if the branch is true and instructions that
  850. annul if the branch is false are supported.
  851.  
  852.    Delay slot scheduling differs from instruction scheduling in that
  853. determining whether an instruction needs a delay slot is dependent only
  854. on the type of instruction being generated, not on data flow between the
  855. instructions.  See the next section for a discussion of data-dependent
  856. instruction scheduling.
  857.  
  858.    The requirement of an insn needing one or more delay slots is
  859. indicated via the `define_delay' expression.  It has the following form:
  860.  
  861.      (define_delay TEST
  862.                    [DELAY-1 ANNUL-TRUE-1 ANNUL-FALSE-1
  863.                     DELAY-2 ANNUL-TRUE-2 ANNUL-FALSE-2
  864.                     ...])
  865.  
  866.    TEST is an attribute test that indicates whether this `define_delay'
  867. applies to a particular insn.  If so, the number of required delay
  868. slots is determined by the length of the vector specified as the second
  869. argument.  An insn placed in delay slot N must satisfy attribute test
  870. DELAY-N.  ANNUL-TRUE-N is an attribute test that specifies which insns
  871. may be annulled if the branch is true.  Similarly, ANNUL-FALSE-N
  872. specifies which insns in the delay slot may be annulled if the branch
  873. is false.  If annulling is not supported for that delay slot, `(nil)'
  874. should be coded.
  875.  
  876.    For example, in the common case where branch and call insns require
  877. a single delay slot, which may contain any insn other than a branch or
  878. call, the following would be placed in the `md' file:
  879.  
  880.      (define_delay (eq_attr "type" "branch,call")
  881.                    [(eq_attr "type" "!branch,call") (nil) (nil)])
  882.  
  883.    Multiple `define_delay' expressions may be specified.  In this case,
  884. each such expression specifies different delay slot requirements and
  885. there must be no insn for which tests in two `define_delay' expressions
  886. are both true.
  887.  
  888.    For example, if we have a machine that requires one delay slot for
  889. branches but two for calls,  no delay slot can contain a branch or call
  890. insn, and any valid insn in the delay slot for the branch can be
  891. annulled if the branch is true, we might represent this as follows:
  892.  
  893.      (define_delay (eq_attr "type" "branch")
  894.         [(eq_attr "type" "!branch,call")
  895.          (eq_attr "type" "!branch,call")
  896.          (nil)])
  897.      
  898.      (define_delay (eq_attr "type" "call")
  899.                    [(eq_attr "type" "!branch,call") (nil) (nil)
  900.                     (eq_attr "type" "!branch,call") (nil) (nil)])
  901.  
  902. 
  903. File: gcc.info,  Node: Function Units,  Prev: Delay Slots,  Up: Insn Attributes
  904.  
  905. Specifying Function Units
  906. -------------------------
  907.  
  908.    On most RISC machines, there are instructions whose results are not
  909. available for a specific number of cycles.  Common cases are
  910. instructions that load data from memory.  On many machines, a pipeline
  911. stall will result if the data is referenced too soon after the load
  912. instruction.
  913.  
  914.    In addition, many newer microprocessors have multiple function
  915. units, usually one for integer and one for floating point, and often
  916. will incur pipeline stalls when a result that is needed is not yet
  917. ready.
  918.  
  919.    The descriptions in this section allow the specification of how much
  920. time must elapse between the execution of an instruction and the time
  921. when its result is used.  It also allows specification of when the
  922. execution of an instruction will delay execution of similar instructions
  923. due to function unit conflicts.
  924.  
  925.    For the purposes of the specifications in this section, a machine is
  926. divided into "function units", each of which execute a specific class
  927. of instructions in first-in-first-out order.  Function units that
  928. accept one instruction each cycle and allow a result to be used in the
  929. succeeding instruction (usually via forwarding) need not be specified.
  930. Classic RISC microprocessors will normally have a single function unit,
  931. which we can call `memory'.  The newer "superscalar" processors will
  932. often have function units for floating point operations, usually at
  933. least a floating point adder and multiplier.
  934.  
  935.    Each usage of a function units by a class of insns is specified with
  936. a `define_function_unit' expression, which looks like this:
  937.  
  938.      (define_function_unit NAME MULTIPLICITY SIMULTANEITY
  939.                            TEST READY-DELAY ISSUE-DELAY
  940.                           [CONFLICT-LIST])
  941.  
  942.    NAME is a string giving the name of the function unit.
  943.  
  944.    MULTIPLICITY is an integer specifying the number of identical units
  945. in the processor.  If more than one unit is specified, they will be
  946. scheduled independently.  Only truly independent units should be
  947. counted; a pipelined unit should be specified as a single unit.  (The
  948. only common example of a machine that has multiple function units for a
  949. single instruction class that are truly independent and not pipelined
  950. are the two multiply and two increment units of the CDC 6600.)
  951.  
  952.    SIMULTANEITY specifies the maximum number of insns that can be
  953. executing in each instance of the function unit simultaneously or zero
  954. if the unit is pipelined and has no limit.
  955.  
  956.    All `define_function_unit' definitions referring to function unit
  957. NAME must have the same name and values for MULTIPLICITY and
  958. SIMULTANEITY.
  959.  
  960.    TEST is an attribute test that selects the insns we are describing
  961. in this definition.  Note that an insn may use more than one function
  962. unit and a function unit may be specified in more than one
  963. `define_function_unit'.
  964.  
  965.    READY-DELAY is an integer that specifies the number of cycles after
  966. which the result of the instruction can be used without introducing any
  967. stalls.
  968.  
  969.    ISSUE-DELAY is an integer that specifies the number of cycles after
  970. the instruction matching the TEST expression begins using this unit
  971. until a subsequent instruction can begin.  A cost of N indicates an N-1
  972. cycle delay.  A subsequent instruction may also be delayed if an
  973. earlier instruction has a longer READY-DELAY value.  This blocking
  974. effect is computed using the SIMULTANEITY, READY-DELAY, ISSUE-DELAY,
  975. and CONFLICT-LIST terms.  For a normal non-pipelined function unit,
  976. SIMULTANEITY is one, the unit is taken to block for the READY-DELAY
  977. cycles of the executing insn, and smaller values of ISSUE-DELAY are
  978. ignored.
  979.  
  980.    CONFLICT-LIST is an optional list giving detailed conflict costs for
  981. this unit.  If specified, it is a list of condition test expressions to
  982. be applied to insns chosen to execute in NAME following the particular
  983. insn matching TEST that is already executing in NAME.  For each insn in
  984. the list, ISSUE-DELAY specifies the conflict cost; for insns not in the
  985. list, the cost is zero.  If not specified, CONFLICT-LIST defaults to
  986. all instructions that use the function unit.
  987.  
  988.    Typical uses of this vector are where a floating point function unit
  989. can pipeline either single- or double-precision operations, but not
  990. both, or where a memory unit can pipeline loads, but not stores, etc.
  991.  
  992.    As an example, consider a classic RISC machine where the result of a
  993. load instruction is not available for two cycles (a single "delay"
  994. instruction is required) and where only one load instruction can be
  995. executed simultaneously.  This would be specified as:
  996.  
  997.      (define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 0)
  998.  
  999.    For the case of a floating point function unit that can pipeline
  1000. either single or double precision, but not both, the following could be
  1001. specified:
  1002.  
  1003.      (define_function_unit
  1004.         "fp" 1 0 (eq_attr "type" "sp_fp") 4 4 [(eq_attr "type" "dp_fp")])
  1005.      (define_function_unit
  1006.         "fp" 1 0 (eq_attr "type" "dp_fp") 4 4 [(eq_attr "type" "sp_fp")])
  1007.  
  1008.    *Note:* The scheduler attempts to avoid function unit conflicts and
  1009. uses all the specifications in the `define_function_unit' expression.
  1010. It has recently come to our attention that these specifications may not
  1011. allow modeling of some of the newer "superscalar" processors that have
  1012. insns using multiple pipelined units.  These insns will cause a
  1013. potential conflict for the second unit used during their execution and
  1014. there is no way of representing that conflict.  We welcome any examples
  1015. of how function unit conflicts work in such processors and suggestions
  1016. for their representation.
  1017.  
  1018. 
  1019. File: gcc.info,  Node: Target Macros,  Next: Config,  Prev: Machine Desc,  Up: Top
  1020.  
  1021. Target Description Macros
  1022. *************************
  1023.  
  1024.    In addition to the file `MACHINE.md', a machine description includes
  1025. a C header file conventionally given the name `MACHINE.h'.  This header
  1026. file defines numerous macros that convey the information about the
  1027. target machine that does not fit into the scheme of the `.md' file.
  1028. The file `tm.h' should be a link to `MACHINE.h'.  The header file
  1029. `config.h' includes `tm.h' and most compiler source files include
  1030. `config.h'.
  1031.  
  1032. * Menu:
  1033.  
  1034. * Driver::              Controlling how the driver runs the compilation passes.
  1035. * Run-time Target::     Defining `-m' options like `-m68000' and `-m68020'.
  1036. * Storage Layout::      Defining sizes and alignments of data.
  1037. * Type Layout::         Defining sizes and properties of basic user data types.
  1038. * Registers::           Naming and describing the hardware registers.
  1039. * Register Classes::    Defining the classes of hardware registers.
  1040. * Stack and Calling::   Defining which way the stack grows and by how much.
  1041. * Varargs::        Defining the varargs macros.
  1042. * Trampolines::         Code set up at run time to enter a nested function.
  1043. * Library Calls::       Controlling how library routines are implicitly called.
  1044. * Addressing Modes::    Defining addressing modes valid for memory operands.
  1045. * Condition Code::      Defining how insns update the condition code.
  1046. * Costs::               Defining relative costs of different operations.
  1047. * Sections::            Dividing storage into text, data, and other sections.
  1048. * PIC::            Macros for position independent code.
  1049. * Assembler Format::    Defining how to write insns and pseudo-ops to output.
  1050. * Debugging Info::      Defining the format of debugging output.
  1051. * Cross-compilation::   Handling floating point for cross-compilers.
  1052. * Misc::                Everything else.
  1053.  
  1054.